home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / raytrace / rayshade / readme.ami < prev    next >
Text File  |  1992-02-21  |  6KB  |  159 lines
  1. February 19, 1992            Amiga Rayshade Readme (port by Colin DeWolfe)
  2. -----------------
  3.  
  4. What we have here in this directory is the current release of Rayshade 4.0.  The purpose
  5. of this readme is not to explain the use of Rayshade in general, but to explain how to
  6. use it on the Amiga.
  7.  
  8.  
  9. Installation
  10. ------------
  11.  
  12.     The only thing you have to do to install rayshade is to copy the file ixemul.library
  13. in the libs directory to LIBS: and add the bin directory to your path.
  14.  
  15.  
  16. The Stack
  17. ---------
  18.  
  19.     Rayshade is a stack pig.  The newest release isn't as much of a pig as the older
  20. revisions were (Thanks Craig) but it still loves stack space. Most of the examples in
  21. the Examples directory can be rendered using a stack of under 200,000 but some exhibit
  22. wierd results if they do run out of stack, especially the constructive solid geometry ones.  
  23. If rayshade does happen to run out of stack one of three things will happen: 1) it will crash
  24. gloriously, 2) the ixemul.library will trap the error and return gracefully to the shell, or
  25. 3) you will just get unpredictable results.  All these seem to depend on how many processes 
  26. you have running and if rayshade's stack ends up running over some other program's data.
  27.     Included is a program called StackWatch (James Locker) which will report stack 
  28. usage every 30'th of a second.  This is great for examining how much stack Rayshade is 
  29. actually using.  It will probably miss alot of peak usage, but it will give you an idea.
  30.  
  31.  
  32. Running Rayshade
  33. ----------------
  34.  
  35.     You run Rayshade by using a CLI command of the following form:
  36.  
  37. 1.drive:dir/dir> rayshade < file.ray > file.mtv [options]
  38.  
  39.     The documents say that you can use the form "rayshade file.ray > file.mtv [options]"
  40. however I had some trouble supporting this with the GNU C pre-processor, so just use the
  41. form above and you will be fine.  I will try to fix this, even if it means switching to 
  42. another pre-processor.
  43.  
  44.     Rayshade will fire up the C pre-processor on your input and then start rendering.
  45.  
  46.  
  47. Documentation
  48. -------------
  49.  
  50.     In the Doc directory are the postscript file for the Guide, Copyright notice,
  51. documentation for some of the support utilities, BUGS, TODO list and other legal stuff.
  52. Some of the utility programs are lacking documentation.  These are: 24toppm, ppmto24,
  53. mtv2tmp, splitanim, and ppmtomtv.  These last three I wrote and have since lost the
  54. source code for (long story).  The other two have notices in the program and did not come
  55. with documentation in the archive that I had.  These will be documented below.
  56.  
  57. Viewing Pictures
  58. ----------------
  59.  
  60.     Once Rayshade has finished cooking you probably want to look at what it did.
  61. Currently there are three methods for doing this.
  62.  
  63. 1)    run mtvtoppm < file.mtv > pipe:a
  64.     ppmtoilbm -hamforce < pipe:a > file.ilbm
  65.     (Then use your favorite display utility or paint program.)
  66.  
  67. 2)    mtvtoppm < file.mtv > file.ppm
  68.     ppmto24 file.ppm file.iff24
  69.     (This will create a 24 bit iff file for you lucky people with 24 bit boards.)
  70.  
  71. 3)      or for preview
  72.  
  73.     mtv2tmp file.mtv file.tmp         (size limit of 320 400)
  74.     ray2 file             (note: no extension)
  75.  
  76.     (Ray2 is taken from DBW Render. It has problems writing a 'correct' ilbm file.
  77.     Most paint programs can load it, but most display viewers can't. Go figure.)
  78.  
  79.  
  80. Image Mapping
  81. -------------
  82.  
  83.     Rayshade supports image mapping.  All the details are in the guide, however
  84. I must mention that it likes its input images in the mtv format.  For this reason
  85. the utilities 24toppm, ilbmtoppm, and ppmtomtv are included.  They have usage guides if you
  86. just type their name at the shell prompt or have a doc file in the Doc. directory.
  87.  
  88.  
  89.  
  90. Animations
  91. ----------
  92.  
  93.     Rayshade has built in animation support as documented in the guide.  It is quite 
  94. basic however and you will probably end up doing animations using C to generate N input 
  95. files.  For those of you who will use the built in animation support, I have included a 
  96. program called splitanim which will split up the sometimes huge image file that is
  97. produced (Rayshade renders all the frames of an animation into one long file.)
  98. The usage is as follows:
  99.  
  100.     splitanim coin.mtv (for the example animation given in the Examples directory)
  101.  
  102. You will be presented with immense disk activity and then after that, a whole plethora
  103. of files named "*.mtv.n" files where * is the base name (in this case coin) and n is the 
  104. frame number.  You can then do with these what you will.
  105.  
  106.  
  107. IT'S NOT A BUG, IT'S A FEATURE
  108. ------------------------------
  109.  
  110.     The GCC support for the pipe: device is abysmal.  So, I had to kludge the 
  111. gcc-cpp support by writing two temporary files, one called pipein and the other
  112. called pipeout.  These are written to the current directory. Pipein is exactly
  113. the same as the original input file and pipeout is the pre-processed input file.
  114. The reason I am saying that it's a feature is because gcc-cpp will sometimes
  115. embed spaces where you don't want them, i.e., in the middle of a file path.
  116. Rayshade will complain about this. What you can then do is edit the file
  117. "pipeout" to fix this and then feed this file into Rayshade like this:
  118.  
  119.     rayshade < pipeout > file.mtv [options]
  120.  
  121. Rayshade will now happily generate your image.
  122. I am going to work on this further, but it may mean moving to another CPP.
  123. Or if anyone has a working version of popen(), mail it to me.
  124. BTW, this problem with gcc-cpp also happens on other platforms (IRIS, SUN...).
  125.  
  126.  
  127.  
  128. Acknowledgements
  129. ----------------
  130.  
  131. For :   Rayshade 4.0:          Craig Kolb of Princeton University
  132.  
  133.     ppmtoilbm:             The German dudes who ported the great PPM toolkit.
  134.                        You know who you are.  (Blatant plug: Get this thing)
  135.  
  136.     ppmto24, 24toppm:    A.J. Brouwer
  137.  
  138.     mtv2tmp, splitanim,    Me.  :-)  (What a self serving little snot, eh?)
  139.     ppmtomtv        
  140.  
  141.     gcc-cpp:        GNU.  Also Markus Wild, who ported it to the Amiga
  142.                 and without who's port of GCC this wouldn't have
  143.                 been possible (SAS and Manx both barfed on the
  144.                 source code.)
  145.  
  146.     Sustainance:        Ron the Pizza Guy
  147. -------------------------------------------------------------------------------
  148.  
  149. Mail messages (no money, this is freely redistributable) can be sent to:
  150.  
  151. Snail (Canada Post):
  152.  
  153. Colin G. DeWolfe        | email:        dewolfe@ug.cs.dal.ca
  154. Unit #2                 |                dewolfe@iris1.ucis.dal.ca
  155. 5254 Green St.,         |                dewolfcg@newton.ccs.tuns.ca
  156. Halifax, Nova Scotia    |
  157. Canada                    
  158. B3H 1N7                    
  159.